Skip to main content

RCS Messaging and Campaign APIs

This page covers the main RCS APIs for capability checks, single-message sending, campaign batching, and callback payloads.

Base URL​

https://alb-backend.msgkart.com/api/v3

Authentication​

Include the following header in every request:

x-api-key: <apikey>

Capability APIs​

Single Capability Discovery​

Checks whether a subscriber is RCS-capable for the given tenant account.

Request Syntax​

GET /capability/{tenantId}/rcs?subscriberId=919999999999

Response Body​

{
  "capable": true
}

Messaging APIs​

Send Single RCS Message (Template)​

Sends a single RCS template message to one subscriber.

Request Syntax​

POST /api/v3/message/{tenantId}/template/rcs

Request Body​

{
  "message": {
    "messageType": "template",
    "name": "msgkart_admin",
    "language": "en_US",
    "components": [
      {
        "componentType": "header",
        "parameters": [
          {
            "type": "media",
            "mediaId": "https://example.com/image.png",
            "mediaType": "image"
          }
        ]
      },
      {
        "componentType": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Test value"
          },
          {
            "type": "text",
            "text": "Test value"
          }
        ]
      }
    ]
  },
  "to": "9994094528"
}

Send Freeform Message​

Sends a freeform text message.

Request Body​

{
  "phone": "919999999999",
  "text": "Hellow World"
}

Response Body​

{
  "messageId": "rcs-5e2a9c41-bd7-8f1e-91b8f2d9a0ef"
}

Campaign APIs​

Create Batched Campaign​

Creates a new RCS campaign. Default expiry is midnight if not provided.

Request Syntax​

POST /promotion/{tenantId}/rcs

Request Body​

{
  "promotionName": "p1Name",
  "promotionExpiry": 1700000000
}

Response Body​

{
  "promotionId": "p1"
}

Add Batch to Campaign​

Adds a batch of subscribers to an existing campaign.

Request Syntax​

POST /promotion/{tenantId}/rcs/batch

Request Body​

{
  "promotionId": "p1",
  "doCapability": false,
  "templateId": "test",
  "components": [
    {
      "type": "BODY",
      "variables": [
        {
          "type": "text",
          "value": "${name}"
        }
      ]
    }
  ],
  "subscribers": [
    {
      "phone": "919999999999",
      "extras": {
        "name": "Juzer",
        "otp": "4521"
      }
    },
    {
      "phone": "919999999998",
      "extras": {
        "name": "Priya",
        "otp": "1234"
      }
    }
  ]
}

Response Body​

{
  "batchId": "batch_123"
}

Callbacks (Webhooks)​

Batched Capability Callback​

POST <Business URL>

Response Body​

{
  "success": true,
  "promotionId": "",
  "batchId": "",
  "totalProcessed": 6,
  "rcsNumbers": [
    "+9198xxxxxx23"
  ],
  "nonRcsNumbers": [
    "+9198xxxxxx24"
  ],
  "rcsCount": 3,
  "nonRcsCount": 3
}

Message Status Callback​

POST <Business URL>

Sent Status Callback​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "messageRef": "aa_cta",
  "subscriberId": "919672242292",
  "status": "sent",
  "sentAt": 1788939562
}

Delivered Status Callback​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "messageRef": "aa_cta",
  "subscriberId": "919672242292",
  "status": "delivered",
  "deliveredAt": 1788939562
}

Read Status Callback​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "messageRef": "aa_cta",
  "subscriberId": "919672242292",
  "status": "read",
  "readAt": 1788939562
}

Failed Status Callback​

{
  "messageId": "wamid.HBgMOTE5NjY4NDEyMDY4FQIAERgSREEwQkYxNjIxMTk5ODRDNddzAA==",
  "messageRef": "aa_cta",
  "subscriberId": "919672242292",
  "status": "failed",
  "failedAt": 1788939562,
  "failureReason": "Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
  "failureDetails": "Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
  "errorCode": 131047
}

End to End Flow​

Create Campaign
↓
Add Batch (with capability check)
↓
Capability Callback (RCS vs Non-RCS users)
↓
Messages Sent
↓
Message Status Callback (Delivered / Read)